From b3f6e95d625ff3dc6fda14152fdd30fdaa4227a1 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Mon, 1 Mar 2021 01:33:06 -0500 Subject: [PATCH] droptargetasync: Convert docs --- gtk/gtkdroptargetasync.c | 138 +++++++++++++++++++-------------------- 1 file changed, 69 insertions(+), 69 deletions(-) diff --git a/gtk/gtkdroptargetasync.c b/gtk/gtkdroptargetasync.c index c14d307096..e9f443cf1d 100644 --- a/gtk/gtkdroptargetasync.c +++ b/gtk/gtkdroptargetasync.c @@ -35,41 +35,38 @@ /** - * SECTION:gtkdroptargetasync - * @Short_description: Event controller to receive DND drops - * @Title: GtkDropTargetAsync - * @See_also: #GtkDropTarget + * GtkDropTargetAsync: + * + * `GtkDropTargetAsync` is an event controller to receive Drag-and-Drop + * operations, asynchronously. * - * GtkDropTargetAsync is an auxiliary object that can be used to receive - * Drag-and-Drop operations. * It is the more complete but also more complex method of handling drop - * operations compared to #GtkDropTarget and you should only use it if - * #GtkDropTarget doesn't provide all the features you need. + * operations compared to [class@Gtk.DropTarget], and you should only use + * it if `GtkDropTarget` doesn't provide all the features you need. * - * To use a #GtkDropTargetAsync to receive drops on a widget, you create - * a #GtkDropTargetAsync object, configure which data formats and actions - * you support, connect to its signals, and then attach - * it to the widget with gtk_widget_add_controller(). + * To use a `GtkDropTargetAsync` to receive drops on a widget, you create + * a `GtkDropTargetAsync` object, configure which data formats and actions + * you support, connect to its signals, and then attach it to the widget + * with [method@Gtk.Widget.add_controller]. * - * During a drag operation, the first signal that a GtkDropTargetAsync - * emits is #GtkDropTargetAsync::accept, which is meant to determine - * whether the target is a possible drop site for the ongoing drop. - * The default handler for the ::accept signal accepts the drop - * if it finds a compatible data format and an action that is supported - * on both sides. + * During a drag operation, the first signal that a `GtkDropTargetAsync` + * emits is [signal@Gtk.DropTargetAsync::accept], which is meant to determine + * whether the target is a possible drop site for the ongoing drop. The + * default handler for the ::accept signal accepts the drop if it finds + * a compatible data format and an action that is supported on both sides. * * If it is, and the widget becomes a target, you will receive a - * #GtkDropTargetAsync::drag-enter signal, followed by - * #GtkDropTargetAsync::drag-motion signals as the pointer moves, - * optionally a #GtkDropTargetAsync::drop signal when a drop happens, - * and finally a #GtkDropTargetAsync::drag-leave signal when the pointer - * moves off the widget. + * [signal@Gtk.DropTargetAsync::drag-enter] signal, followed by + * [signal@Gtk.DropTargetAsync::drag-motion] signals as the pointer moves, + * optionally a [signal@Gtk.DropTargetAsync::drop] signal when a drop happens, + * and finally a [signal@Gtk.DropTargetAsync::drag-leave] signal when the + * pointer moves off the widget. * - * The ::drag-enter and ::drag-motion handler return a #GdkDragAction + * The ::drag-enter and ::drag-motion handler return a `GdkDragAction` * to update the status of the ongoing operation. The ::drop handler * should decide if it ultimately accepts the drop and if it does, it * should initiate the data transfer and finish the operation by calling - * gdk_drop_finish(). + * [method@Gdk.Drop.finish]. * * Between the ::drag-enter and ::drag-leave signals the widget is a * current drop target, and will receive the %GTK_STATE_FLAG_DROP_ACTIVE @@ -383,19 +380,19 @@ gtk_drop_target_async_class_init (GtkDropTargetAsyncClass *class) class->drop = gtk_drop_target_async_drop; /** - * GtkDropTargetAsync:actions: + * GtkDropTargetAsync:actions: (attributes org.gtk.Property.get=gtk_drop_target_async_get_actions org.gtk.Property.set=gtk_drop_target_async_set_actions) * - * The #GdkDragActions that this drop target supports - */ + * The `GdkDragActions` that this drop target supports. + */ properties[PROP_ACTIONS] = g_param_spec_flags ("actions", P_("Actions"), P_("Actions"), GDK_TYPE_DRAG_ACTION, 0, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS | G_PARAM_EXPLICIT_NOTIFY); /** - * GtkDropTargetAsync:formats: + * GtkDropTargetAsync:formats: (attributes org.gtk.Property.get=gtk_drop_target_async_get_formats org.gtk.Property.set=gtk_drop_target_async_set_formats) * - * The #GdkContentFormats that determines the supported data formats + * The `GdkContentFormats` that determines the supported data formats. */ properties[PROP_FORMATS] = g_param_spec_boxed ("formats", P_("Formats"), P_("Formats"), @@ -406,16 +403,16 @@ gtk_drop_target_async_class_init (GtkDropTargetAsyncClass *class) /** * GtkDropTargetAsync::accept: - * @self: the #GtkDropTargetAsync + * @self: the `GtkDropTargetAsync` * @drop: the #GdkDrop * - * The ::accept signal is emitted on the drop site when a drop operation - * is about to begin. + * Emitted on the drop site when a drop operation is about to begin. * * If the drop is not accepted, %FALSE will be returned and the drop target * will ignore the drop. If %TRUE is returned, the drop is accepted for now - * but may be rejected later via a call to gtk_drop_target_async_reject() or - * ultimately by returning %FALSE from #GtkDropTargetAsync::drop. + * but may be rejected later via a call to [method@Gtk.DropTargetAsync.reject_drop] + * or ultimately by returning %FALSE from a [signal@Gtk.DropTargetAsync::drop] + * handler. * * The default handler for this signal decides whether to accept the drop * based on the formats provided by the @drop. @@ -423,7 +420,7 @@ gtk_drop_target_async_class_init (GtkDropTargetAsyncClass *class) * If the decision whether the drop will be accepted or rejected needs * further processing, such as inspecting the data, this function should * return %TRUE and proceed as is @drop was accepted and if it decides to - * reject the drop later, it should call gtk_drop_target_async_reject_drop(). + * reject the drop later, it should call [method@Gtk.DropTargetAsync.reject_drop]. * * Returns: %TRUE if @drop is accepted */ @@ -439,15 +436,16 @@ gtk_drop_target_async_class_init (GtkDropTargetAsyncClass *class) /** * GtkDropTargetAsync::drag-enter: - * @self: the #GtkDropTargetAsync + * @self: the `GtkDropTargetAsync` * @drop: the #GdkDrop * @x: the x coordinate of the current pointer position * @y: the y coordinate of the current pointer position * - * The ::drag-enter signal is emitted on the drop site when the pointer - * enters the widget. It can be used to set up custom highlighting. + * Emitted on the drop site when the pointer enters the widget. + * + * It can be used to set up custom highlighting. * - * Returns: Preferred action for this drag operation. + * Returns: Preferred action for this drag operation. */ signals[DRAG_ENTER] = g_signal_new (I_("drag-enter"), @@ -461,15 +459,14 @@ gtk_drop_target_async_class_init (GtkDropTargetAsyncClass *class) /** * GtkDropTargetAsync::drag-motion: - * @self: the #GtkDropTargetAsync + * @self: the `GtkDropTargetAsync` * @drop: the #GdkDrop * @x: the x coordinate of the current pointer position * @y: the y coordinate of the current pointer position * - * The ::drag-motion signal is emitted while the pointer is moving - * over the drop target. + * Emitted while the pointer is moving over the drop target. * - * Returns: Preferred action for this drag operation. + * Returns: Preferred action for this drag operation. */ signals[DRAG_MOTION] = g_signal_new (I_("drag-motion"), @@ -483,12 +480,13 @@ gtk_drop_target_async_class_init (GtkDropTargetAsyncClass *class) /** * GtkDropTargetAsync::drag-leave: - * @self: the #GtkDropTargetAsync + * @self: the `GtkDropTargetAsync` * @drop: the #GdkDrop * - * The ::drag-leave signal is emitted on the drop site when the pointer - * leaves the widget. Its main purpose it to undo things done in - * #GtkDropTargetAsync::drag-enter. + * Emitted on the drop site when the pointer leaves the widget. + * + * Its main purpose it to undo things done in + * `GtkDropTargetAsync`::drag-enter. */ signals[DRAG_LEAVE] = g_signal_new (I_("drag-leave"), @@ -502,23 +500,25 @@ gtk_drop_target_async_class_init (GtkDropTargetAsyncClass *class) /** * GtkDropTargetAsync::drop: - * @self: the #GtkDropTargetAsync + * @self: the `GtkDropTargetAsync` * @drop: the #GdkDrop * @x: the x coordinate of the current pointer position * @y: the y coordinate of the current pointer position * - * The ::drop signal is emitted on the drop site when the user drops - * the data onto the widget. The signal handler must determine whether - * the pointer position is in a drop zone or not. If it is not in a drop - * zone, it returns %FALSE and no further processing is necessary. + * Emitted on the drop site when the user drops the data onto the widget. + * + * The signal handler must determine whether the pointer position is in a + * drop zone or not. If it is not in a drop zone, it returns %FALSE and no + * further processing is necessary. * * Otherwise, the handler returns %TRUE. In this case, this handler will - * accept the drop. The handler must ensure that gdk_drop_finish() is - * called to let the source know that the drop is done. The call to - * gdk_drop_finish() must only be done when all data has been received. + * accept the drop. The handler must ensure that [method@Gdk.Drop.finish] + * is called to let the source know that the drop is done. The call to + * [method@Gdk.Drop.finish] must only be done when all data has been received. * - * To receive the data, use one of the read functions provides by #GdkDrop - * such as gdk_drop_read_async() or gdk_drop_read_value_async(). + * To receive the data, use one of the read functions provided by + * [class@Gdk.Drop] such as [method@Gdk.Drop.read_async] or + * [method@Gdk.Drop.read_value_async]. * * Returns: whether the drop is accepted at the given pointer position */ @@ -543,9 +543,9 @@ gtk_drop_target_async_init (GtkDropTargetAsync *self) * @formats: (nullable) (transfer full): the supported data formats * @actions: the supported actions * - * Creates a new #GtkDropTargetAsync object. + * Creates a new `GtkDropTargetAsync` object. * - * Returns: the new #GtkDropTargetAsync + * Returns: the new `GtkDropTargetAsync` */ GtkDropTargetAsync * gtk_drop_target_async_new (GdkContentFormats *formats, @@ -564,8 +564,8 @@ gtk_drop_target_async_new (GdkContentFormats *formats, } /** - * gtk_drop_target_async_set_formats: - * @self: a #GtkDropTargetAsync + * gtk_drop_target_async_set_formats: (attributes org.gtk.Method.set_property=formats) + * @self: a `GtkDropTargetAsync` * @formats: (nullable): the supported data formats or %NULL for * any format. * @@ -592,8 +592,8 @@ gtk_drop_target_async_set_formats (GtkDropTargetAsync *self, } /** - * gtk_drop_target_async_get_formats: - * @self: a #GtkDropTargetAsync + * gtk_drop_target_async_get_formats: (attributes org.gtk.Method.get_property=formats) + * @self: a `GtkDropTargetAsync` * * Gets the data formats that this drop target accepts. * @@ -610,8 +610,8 @@ gtk_drop_target_async_get_formats (GtkDropTargetAsync *self) } /** - * gtk_drop_target_async_set_actions: - * @self: a #GtkDropTargetAsync + * gtk_drop_target_async_set_actions: (attributes org.gtk.Method.set_property=actions) + * @self: a `GtkDropTargetAsync` * @actions: the supported actions * * Sets the actions that this drop target supports. @@ -631,8 +631,8 @@ gtk_drop_target_async_set_actions (GtkDropTargetAsync *self, } /** - * gtk_drop_target_async_get_actions: - * @self: a #GtkDropTargetAsync + * gtk_drop_target_async_get_actions: (attributes org.gtk.Method.get_property=actions) + * @self: a `GtkDropTargetAsync` * * Gets the actions that this drop target supports. * @@ -648,7 +648,7 @@ gtk_drop_target_async_get_actions (GtkDropTargetAsync *self) /** * gtk_drop_target_async_reject_drop: - * @self: a #GtkDropTargetAsync + * @self: a `GtkDropTargetAsync` * @drop: the #GdkDrop of an ongoing drag operation * * Sets the @drop as not accepted on this drag site. -- 2.30.2